~ chicken-core (chicken-5) /manual/Module (chicken file posix)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken file posix)56This module provides various operations on files and directories that7are more POSIX-oriented than the generic higher-level operations from8[[Module (chicken file)]].910Note that the following definitions are not all available on non-UNIX11systems like Windows. See below for Windows specific notes.1213All errors related to failing file-operations will signal a condition14of kind {{(exn i/o file)}}.1516* New in CHICKEN 5.4.0: Errors caused by underlying C calls that17 change errno will produce a condition object with an {{errno}}18 property, which can be accessed with19 {{(get-condition-property <the-condition-object> 'exn 'errno)}}.2021=== Constants2223==== File-control Commands2425<constant>fcntl/dupfd</constant><br>26<constant>fcntl/getfd</constant><br>27<constant>fcntl/setfd</constant><br>28<constant>fcntl/getfl</constant><br>29<constant>fcntl/setfl</constant>3031Operations used with {{file-control}}.3233'''NOTE''': On native Windows builds (all except cygwin), these are34all defined as zero. The {{file-control}} procedure to use these with35is also unimplemented and will raise an error when called.3637==== File positions3839<constant>seek/cur</constant><br>40<constant>seek/set</constant><br>41<constant>seek/end</constant><br>4243File positions for {{set-file-position!}}.4445==== Standard I/O file-descriptors4647<constant>fileno/stdin</constant><br>48<constant>fileno/stdout</constant><br>49<constant>fileno/stderr</constant>5051Standard I/O file descriptor numbers, used with procedures52such as {{open-input-file*}} which take file descriptors.5354==== Open flags5556<constant>open/rdonly</constant><br>57<constant>open/wronly</constant><br>58<constant>open/rdwr</constant><br>59<constant>open/read</constant><br>60<constant>open/write</constant><br>61<constant>open/creat</constant><br>62<constant>open/append</constant><br>63<constant>open/excl</constant><br>64<constant>open/noctty</constant><br>65<constant>open/nonblock</constant><br>66<constant>open/trunc</constant><br>67<constant>open/sync</constant><br>68<constant>open/fsync</constant><br>69<constant>open/binary</constant><br>70<constant>open/text</constant>7172Open flags used with the {{file-open}} procedure. {{open/read}} is a73convenience synonym for {{open/rdonly}}, as is {{open/write}}74for {{open/wronly}}.7576'''NOTE''': On native Windows builds (all except cygwin),77{{open/noctty}}, {{open/nonblock}}, {{open/fsync}} and {{open/sync}}78are defined as zero because the corresponding flag doesn't exist.79This means you can safely add these to any set of flags when opening a80file or pipe, but it simply won't have an effect.8182==== Open flags for create-pipe8384<constant>open/noinherit</constant>8586This variable is a mode value for {{create-pipe}}. Useful when87spawning a child process on Windows. On UNIX it is defined as zero,88so you can safely pass it there, but it will have no effect.899091==== Permission bits9293<constant>perm/irusr</constant><br>94<constant>perm/iwusr</constant><br>95<constant>perm/ixusr</constant><br>96<constant>perm/irgrp</constant><br>97<constant>perm/iwgrp</constant><br>98<constant>perm/ixgrp</constant><br>99<constant>perm/iroth</constant><br>100<constant>perm/iwoth</constant><br>101<constant>perm/ixoth</constant><br>102<constant>perm/irwxu</constant><br>103<constant>perm/irwxg</constant><br>104<constant>perm/irwxo</constant><br>105<constant>perm/isvtx</constant><br>106<constant>perm/isuid</constant><br>107<constant>perm/isgid</constant>108109Permission bits used with, for example, {{file-open}}.110111'''NOTE''': On native Windows builds (all except cygwin),112{{perm/isvtx}}, {{perm/isuid}} and {{perm/isgid}} are defined as zero113because the corresponding permission doesn't exist. This means you114can safely add these to any set of flags when opening a file or pipe,115but it simply won't have an effect.116117118=== Information about files119120==== directory?121122<procedure>(directory? FILE)</procedure>123124Returns {{#t}} if {{FILE}} designates a directory. Otherwise, it returns {{#f}}.125{{FILE}} may be a pathname, a file-descriptor or a port object.126127128==== file-type129130<procedure>(file-type FILE [LINK [ERROR]])</procedure>131132Returns the file-type for {{FILE}}, which should be a filename, a file-descriptor133or a port object. If {{LINK}} is given and true, symbolic-links are134not followed:135136 regular-file137 directory138 fifo139 socket140 symbolic-link141 character-device142 block-device143144Note that not all types are supported on every platform.145If {{ERROR}} is given and false, then {{file-type}} returns {{#f}} if the file does not exist;146otherwise, it signals an error.147148==== character-device?149==== block-device?150==== socket?151152<procedure>(character-device? FILE)</procedure><br>153<procedure>(block-device? FILE)</procedure><br>154<procedure>(socket? FILE)</procedure>155156These procedures return {{#t}} if {{FILE}} given is of the157appropriate type. {{FILE}} may be a filename, a file-descriptor or a port object.158Note that these operations follow symbolic links. If the file does159not exist, {{#f}} is returned.160161==== regular-file?162163<procedure>(regular-file? FILE)</procedure>164165Returns true, if {{FILE}} names a regular file (not a directory, socket, etc.) This operation follows symbolic links; use either {{symbolic-link?}} or {{file-type}} if you need to test for symlinks. {{FILE}} may refer to a filename, file descriptor or ports object.166167168=== Fifos169170==== create-fifo171172<procedure>(create-fifo FILENAME [MODE])</procedure>173174Creates a FIFO with the name {{FILENAME}} and the permission bits175{{MODE}}, which defaults to176177<enscript highlight=scheme>178 (+ perm/irwxu perm/irwxg perm/irwxo)179</enscript>180181'''NOTE''': On native Windows builds (all except cygwin), this182procedure is unimplemented and will raise an error.183184==== fifo?185186<procedure>(fifo? FILE)</procedure>187188Returns {{#t}} if {{FILE}} names a FIFO. {{FILE}} may be a filename,189a port or a file-descriptor.190191192=== Retrieving file attributes193194==== file-access-time195==== file-change-time196==== file-modification-time197<procedure>(file-access-time FILE)</procedure><br>198<procedure>(file-change-time FILE)</procedure><br>199<procedure>(file-modification-time FILE)</procedure>200201Returns time (in seconds) of the last access, inode change or content202modification of {{FILE}}, respectively. {{FILE}} may be a filename, a203file-descriptor or a file-backed port. If the file does not exist, an204error is signaled.205206==== set-file-times!207208<procedure>(set-file-times! FILE [MTIME [ATIME]])</procedure>209210Sets the time of last modification {{MTIME}} and/or time of last211access {{ATIME}} (in seconds) for {{FILE}}. {{FILE}} may be a212filename, a file-descriptor or a file-backed port. If the file does213not exist, an error is signaled.214215If neither {{MTIME}} nor {{ATIME}} is supplied, the current time is216used. If only {{MTIME}} is supplied, {{ATIME}} will be set to the217same value. If an argument is {{#f}}, it will not be changed.218219Consequently, if only {{MTIME}} is passed and it is {{#f}}, {{ATIME}}220is assumed to be {{#f}} as well and neither will be changed.221222223==== file-stat224225<procedure>(file-stat FILE [LINK])</procedure>226227Returns a 13-element vector with the following contents:228229<table>230<tr><th>index</th>231 <th>value</th>232 <th>field</th>233 <th>notes</th></tr>234<tr><td>0</td>235 <td>inode number</td>236 <td>{{st_ino}}</td>237 <td></td></tr>238<tr><td>1</td>239 <td>mode</td>240 <td>{{st_mode}}</td>241 <td>bitfield combining file permissions and file type</td></tr>242<tr><td>2</td>243 <td>number of hard links</td>244 <td>{{st_nlink}}</td>245 <td></td></tr>246<tr><td>3</td>247 <td>UID of owner</td>248 <td>{{st_uid}}</td>249 <td>as with {{file-owner}}</td></tr>250<tr><td>4</td>251 <td>GID of owner</td>252 <td>{{st_gid}}</td>253 <td></td></tr>254<tr><td>5</td>255 <td>size</td>256 <td>{{st_size}}</td>257 <td>as with {{file-size}}</td></tr>258<tr><td>6</td>259 <td>access time</td>260 <td>{{st_atime}}</td>261 <td>as with {{file-access-time}}</td></tr>262<tr><td>7</td>263 <td>change time</td>264 <td>{{st_ctime}}</td>265 <td>as with {{file-change-time}}</td></tr>266<tr><td>8</td>267 <td>modification time</td>268 <td>{{st_mtime}}</td>269 <td>as with {{file-modification-time}}</td></tr>270<tr><td>9</td>271 <td>parent device ID </td>272 <td>{{st_dev}}</td>273 <td>ID of device on which this file resides</td></tr>274<tr><td>10</td>275 <td>device ID</td>276 <td>{{st_rdev}}</td>277 <td>device ID for special files (i.e. the raw major/minor number)</td></tr>278<tr><td>11</td>279 <td>block size</td>280 <td>{{st_blksize}}</td>281 <td></td></tr>282<tr><td>12</td>283 <td>number of blocks allocated</td>284 <td>{{st_blocks}}</td>285 <td></td></tr>286</table>287288On Windows systems, the last 4 values are undefined.289290By default, symbolic links are followed and291the status of the referenced file is returned;292however, if the optional argument {{LINK}} is given and293not {{#f}}, the status of the link itself is returned.294295{{FILE}} may be a filename, port or file-descriptor.296297Note that for very large files, the {{file-size}} value may be an298inexact integer.299300==== file-position301302<procedure>(file-position FILE)</procedure>303304Returns the current file position of {{FILE}}, which should be a305port or a file-descriptor.306307==== file-size308309<procedure>(file-size FILE)</procedure>310311Returns the size of the file designated by {{FILE}}. {{FILE}}312may be a filename, a file-descriptor or a port object. If the file does not exist,313an error is signaled. Note that for very large files, {{file-size}} may314return an inexact integer.315316==== file-owner317318<procedure>(file-owner FILE)</procedure>319320Returns the user-id of {{FILE}} (an exact integer). {{FILE}} may be a321filename, a file-descriptor or a port object.322323==== set-file-owner!324325<procedure>(set-file-owner! FILE UID)</procedure>326<procedure>(set! (file-owner FILE) UID)</procedure>327328Changes the ownership of {{FILE}} to user-id {{UID}} (which should be329an exact integer) using the {{chown()}} system call. {{FILE}} may be330a filename, a file-descriptor or a port object.331332'''NOTE''': On native Windows builds (all except cygwin), this333procedure is unimplemented and will raise an error.334335==== file-group336337<procedure>(file-group FILE)</procedure>338339Returns the group-id of {{FILE}}. {{FILE}} may be a filename, a340file-descriptor or a port object.341342==== set-file-group!343344<procedure>(set-file-group! FILE GID)</procedure>345<procedure>(set! (file-group FILE) GID)</procedure>346347Changes the group ownership of {{FILE}} to group-id {{GID}} (which348should be an exact integer) using the {{chgrp()}} system call.349{{FILE}} may be a filename, a file-descriptor or a port object.350351'''NOTE''': On native Windows builds (all except cygwin), this352procedure is unimplemented and will raise an error.353354355==== file-permissions356357<procedure>(file-permissions FILE)</procedure>358359Returns the permission bits for {{FILE}}. You can test this value360by performing bitwise operations on the result and the {{perm/...}}361values. {{FILE}} may be a filename, a file-descriptor or a port object.362363==== set-file-permissions!364365<procedure>(set-file-permissions! FILE MODE)</procedure>366<procedure>(set! (file-permissions FILE) MODE)</procedure>367368Changes the current permission bits for {{FILE}} to {{MODE}} using the369{{chmod()}} system call. The {{perm/...}} variables contain the370various permission bits and can be combinded with the {{bitwise-ior}}371procedure. {{FILE}} may be a filename, a file-descriptor or a port372object, {{MODE}} should be a fixnum.373374375==== file-truncate376377<procedure>(file-truncate FILE OFFSET)</procedure>378379Truncates the file {{FILE}} to the length {{OFFSET}},380which should be an integer. If the file-size is smaller or equal to381{{OFFSET}} then nothing is done. {{FILE}} should be a filename,382a file-descriptor or a port object.383384'''NOTE''': On native Windows builds (all except cygwin), this385procedure is unimplemented and will raise an error.386387==== set-file-position!388389<procedure>(set-file-position! FILE POSITION [WHENCE])</procedure><br>390<procedure>(set! (file-position FILE) POSITION)</procedure>391392Sets the current read/write position of {{FILE}} to393{{POSITION}}, which should be an exact integer. {{FILE}}394should be a port or a file-descriptor. {{WHENCE}} specifies395how the position is to interpreted and should be one of the values396{{seek/set, seek/cur}} and {{seek/end}}. It defaults to397{{seek/set}}.398399Exceptions: {{(exn bounds)}}, {{(exn i/o file)}}400401402==== file-creation-mode403404<procedure>(file-creation-mode [MODE])</procedure>405406Returns the initial file permissions used for newly created files407(as with {{umask(2)}}). If {{MODE}} is supplied, the mode is408changed to this value. You can set the mode by executing409410 (set! (file-creation-mode) MODE)411412or413414 (file-creation-mode MODE)415416where {{MODE}} is a bitwise combination of one or more of417the {{perm/...}} flags.418419420=== Hard and symbolic links421422==== file-link423424<procedure>(file-link OLDNAME NEWNAME)</procedure>425426Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).427428429==== symbolic-link?430431<procedure>(symbolic-link? FILE)</procedure>432433Returns true, if {{FILE}} names a symbolic link. If no such file exists, {{#f}}434is returned. This operation does not follow symbolic links itself.435{{FILE}} could be a filename, file descriptor or port object.436437==== create-symbolic-link438439<procedure>(create-symbolic-link OLDNAME NEWNAME)</procedure>440441Creates a symbolic link with the filename {{NEWNAME}} that points442to the file named {{OLDNAME}}.443444'''NOTE''': On native Windows builds (all except cygwin), this445procedure is unimplemented and will raise an error.446447==== read-symbolic-link448449<procedure>(read-symbolic-link FILENAME [CANONICALIZE])</procedure>450451Returns the filename to which the symbolic link {{FILENAME}} points.452If {{CANONICALIZE}} is given and true, then symbolic links are453resolved repeatedly until the result is not a link.454455'''NOTE''': On native Windows builds (all except cygwin), this456procedure is unimplemented and will raise an error.457458459=== File descriptors and low-level I/O460461==== duplicate-fileno462463<procedure>(duplicate-fileno OLD [NEW])</procedure>464465If {{NEW}} is given, then the file-descriptor {{NEW}} is opened466to access the file with the file-descriptor {{OLD}}. Otherwise a467fresh file-descriptor accessing the same file as {{OLD}} is returned.468469==== file-close470471<procedure>(file-close FILENO)</procedure>472473Closes the input/output file with the file-descriptor {{FILENO}}.474475==== file-open476477<procedure>(file-open FILENAME FLAGS [MODE])</procedure>478479Opens the file specified with the string {{FILENAME}} and open-flags480{{FLAGS}} using the C function {{open(2)}}. On success a481file-descriptor for the opened file is returned.482483{{FLAGS}} is a bitmask of {{open/...}}484values '''or'''ed together using {{bitwise-ior}} (or simply added485together). You must provide exactly one of the access flags {{open/rdonly}}, {{open/wronly}}, or {{open/rdwr}}. Additionally, you may provide zero or more creation flags ({{open/creat}}, {{open/excl}}, {{open/trunc}}, and {{open/noctty}}) and status flags (the remaining {{open/...}} values). For example, to open a possibly new output file for appending:486487 (file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))488489The optional {{MODE}} should be a bitmask composed of one490or more permission values like {{perm/irusr}} and is only relevant491when a new file is created. The default mode is492{{perm/irwxu | perm/irgrp | perm/iroth}}.493494==== file-mkstemp495496<procedure>(file-mkstemp TEMPLATE-FILENAME)</procedure>497498Create a file based on the given {{TEMPLATE-FILENAME}}, in which499the six last characters must be ''XXXXXX''. These will be replaced500with a string that makes the filename unique. The file descriptor of501the created file and the generated filename is returned. See the502{{mkstemp(3)}} manual page for details on how this function503works. The template string given is not modified.504505Example usage:506507<enscript highlight=scheme>508 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))509 (let ((temp-port (open-output-file* fd)))510 (format temp-port "This file is ~A.~%" temp-path)511 (close-output-port temp-port)))512</enscript>513514==== file-read515516<procedure>(file-read FILENO SIZE [BUFFER])</procedure>517518Reads {{SIZE}} bytes from the file with the file-descriptor519{{FILENO}}. If a string or bytevector is passed in the optional520argument {{BUFFER}}, then this string will be destructively modified521to contain the read data. This procedure returns a list with two values:522the buffer containing the data and the number of bytes read.523524==== file-select525526<procedure>(file-select READFDLIST WRITEFDLIST [TIMEOUT])</procedure>527528Waits until any of the file-descriptors given in the lists529{{READFDLIST}} and {{WRITEFDLIST}} is ready for input or530output, respectively. If the optional argument {{TIMEOUT}} is531given and not false, then it should specify the number of seconds after532which the wait is to be aborted (the value may be a float). This procedure returns two values:533the lists of file-descriptors ready for input and output, respectively.534{{READFDLIST}} and {{WRITEFDLIST}} may also be file-descriptors535instead of lists. In this case the returned values are booleans536indicating whether input/output is ready by {{#t}} or {{#f}}537otherwise. You can also pass {{#f}} as {{READFDLIST}} or538{{WRITEFDLIST}} argument, which is equivalent to {{()}}.539540'''NOTE''': On native Windows builds (all except cygwin), this541procedure is unimplemented and will raise an error.542543==== file-write544545<procedure>(file-write FILENO BUFFER [SIZE])</procedure>546547Writes the contents of the string or bytevector {{BUFFER}} into548the file with the file-descriptor {{FILENO}}. If the optional549argument {{SIZE}} is given, then only the specified number of bytes550are written.551552==== file-control553554<procedure>(file-control FILENO COMMAND [ARGUMENT])</procedure>555556Performs the fcntl operation {{COMMAND}} with the given557{{FILENO}} and optional {{ARGUMENT}}. The return value is558meaningful depending on the {{COMMAND}}.559560'''NOTE''': On native Windows builds (all except cygwin), this561procedure is unimplemented and will raise an error.562563==== open-input-file*564==== open-output-file*565566<procedure>(open-input-file* FILENO [OPENMODE])</procedure><br>567<procedure>(open-output-file* FILENO [OPENMODE])</procedure>568569Opens file for the file-descriptor {{FILENO}} for input or output570and returns a port. {{FILENO}} should be a positive exact integer.571{{OPENMODE}} specifies an additional mode for opening the file572(currently only the keyword {{#:append}} is supported, which opens573an output-file for appending).574575==== port->fileno576577<procedure>(port->fileno PORT)</procedure>578579If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for580this port. Otherwise an error is signaled.581582583=== Record locking584585These procedures are all unsupported on native Windows builds (all586except cygwin).587588==== file-lock589590<procedure>(file-lock PORT [START [LEN]])</procedure>591592Locks the file associated with {{PORT}} for reading or593writing (according to whether {{PORT}} is an input- or594output-port). {{START}} specifies the starting position in the595file to be locked and defaults to 0. {{LEN}} specifies the length596of the portion to be locked and defaults to {{#t}}, which means597the complete file. {{file-lock}} returns a ''lock''-object.598599'''NOTE''': On native Windows builds (all except cygwin), this600procedure is unimplemented and will raise an error.601602==== file-lock/blocking603604<procedure>(file-lock/blocking PORT [START [LEN]])</procedure>605606Similar to {{file-lock}}, but if a lock is held on the file,607the current process blocks (including all threads) until the lock is released.608609'''NOTE''': On native Windows builds (all except cygwin), this610procedure is unimplemented and will raise an error.611612==== file-test-lock613614<procedure>(file-test-lock PORT [START [LEN]])</procedure>615616Tests whether the file associated with {{PORT}} is locked for reading617or writing (according to whether {{PORT}} is an input- or output-port)618and returns either {{#f}} or the process-id of the locking process.619620'''NOTE''': On native Windows builds (all except cygwin), this621procedure is unimplemented and will raise an error.622623==== file-unlock624625<procedure>(file-unlock LOCK)</procedure>626627Unlocks the previously locked portion of a file given in {{LOCK}}.628629'''NOTE''': On native Windows builds (all except cygwin), this630procedure is unimplemented and will raise an error.631632---633Previous: [[Module (chicken file)]]634635Next: [[Module (chicken fixnum)]]636